Plan: Make CRD API reference docs read like YAML (nested + less verbose)

Context / Why

The current generated API reference docs (e.g. docs/reference/api/coderprovisioner.md) are hard for users to act on:

• The Field column repeats spec. / status. even though the table is already under ## Spec / ## Status.
• The Type column shows fully-qualified Go package paths, which is noisy.
• Most importantly, nested struct types are opaque (e.g. controlPlaneRef is a corev1.LocalObjectReference, but the docs don’t show that the YAML must contain name:). Users don’t know what to write.

Goal: adjust the crd-ref-docs markdown template so the output is:

• easier to scan,
• closer to the YAML structure people actually write,
• and provides actionable detail for “object” fields (at least for the important/commonly-confusing ones like LocalObjectReference).

Evidence (what we verified)

• API reference docs are generated by crd-ref-docs via hack/update-reference-docs.sh / make docs-reference. (hack/update-reference-docs.sh, hack/crd-ref-docs/config.yaml)
• Output is a simple flat table produced by hack/crd-ref-docs/templates/markdown/gv_list.tpl.
• The example in the screenshot matches docs/reference/api/coderprovisioner.md.
• crd-ref-docs represents nested types via types.Type with a Members() method that returns struct fields even through aliases/slices/pointers. (vendor/github.com/elastic/crd-ref-docs/types/types.go)

Implementation details

1) Remove redundant spec. / status. prefixes

File: hack/crd-ref-docs/templates/markdown/gv_list.tpl

• Change the rows under ## Spec from:

| `spec.{{ $member.Name }}` | ... |

to:

| `{{ $member.Name }}` | ... |

• Change the rows under ## Status from:

| `status.{{ $member.Name }}` | ... |

to:

| `{{ $member.Name }}` | ... |

Result: tables read like the YAML keys a user will set under spec: / status:.

2) Bonus: Clean up verbose Go type paths in the Type column

File: hack/crd-ref-docs/templates/markdown/gv_list.tpl (the typeName helper)

Update typeName to replace noisy package paths with common aliases / short names.

Proposed replacements (minimal, focused on what we see in our CRDs):

• k8s.io/apimachinery/pkg/apis/meta/v1. → metav1. (already present)
• k8s.io/api/core/v1. → corev1.
• github.com/coder/coder-k8s/api/v1alpha1. → `` (strip to just the type name)

Shape:

{{- $typeString := $fieldType.String -}}
{{- $typeString = trimPrefix "*" $typeString -}}
{{- $typeString = $typeString | replace "k8s.io/apimachinery/pkg/apis/meta/v1." "metav1." -}}
{{- $typeString = $typeString | replace "k8s.io/api/core/v1." "corev1." -}}
{{- $typeString = $typeString | replace "github.com/coder/coder-k8s/api/v1alpha1." "" -}}
{{- $typeString -}}

Result: types become readable (corev1.LocalObjectReference, CoderProvisionerKeySpec, etc.) without losing meaning.

3) Show nested fields for selected “object” types (so users know what to write)

File: hack/crd-ref-docs/templates/markdown/gv_list.tpl

Replace the flat range $specMembers / range $statusMembers rendering with a small recursive renderer that can optionally expand struct members.

3.1) Expansion policy (avoid doc bloat)

We should not blindly expand every imported Kubernetes type (e.g. corev1.EnvVar can recursively explode). Instead, expand only when:

• The field’s type has members (len $t.Members > 0), and
• The type is either:
  • Project-local ($t.Package starts with github.com/coder/coder-k8s/api/), or
  • A small, commonly-confusing external wrapper like k8s.io/api/core/v1.LocalObjectReference.

Add a simple depth limit (e.g. maxDepth := 3) to prevent runaway recursion.

3.2) Table rendering shape

Add a new template block (name is flexible) that prints rows for a list of fields and can recurse:

{{- define "renderFields" -}}
{{- $fields := index . 0 -}}
{{- $depth := index . 1 -}}
{{- $maxDepth := index . 2 -}}
{{- $indent := repeat $depth "  " -}}

{{- range $f := $fields }}
{{- if not $f.Type -}}
{{ fail (printf "field %q is missing type information" $f.Name) }}
{{- end -}}

{{- $t := $f.Type -}}
{{- $hasMembers := gt (len $t.Members) 0 -}}
{{- $isProjectLocal := hasPrefix $t.Package "github.com/coder/coder-k8s/api/" -}}
{{- $isLocalObjectRef := and (eq $t.Package "k8s.io/api/core/v1") (eq $t.Name "LocalObjectReference") -}}
{{- $shouldExpand := and $hasMembers (lt $depth $maxDepth) (or $isProjectLocal $isLocalObjectRef) -}}

| {{ $indent }}`{{ $f.Name }}` | `{{ template "typeName" $t }}` | {{ markdownRenderFieldDoc $f.Doc }} |
{{- if $shouldExpand }}
{{- template "renderFields" (list $t.Members (add $depth 1) $maxDepth) -}}
{{- end }}
{{- end }}
{{- end -}}

Then render spec/status like:

## Spec

| Field | Type | Description |
| --- | --- | --- |
{{- template "renderFields" (list $specMembers 0 3) }}

## Status

| Field | Type | Description |
| --- | --- | --- |
{{- template "renderFields" (list $statusMembers 0 3) }}

Result: users will see controlPlaneRef → name (and other small structs) directly in the table, without needing to understand Go types.

4) Regenerate reference docs and confirm output

After template changes, regenerate docs so the repo reflects the new format.

• Run: make docs-reference (or bash hack/update-reference-docs.sh)
• Confirm:
  • docs/reference/api/coderprovisioner.md no longer has spec. / status. prefixes.
  • controlPlaneRef expands to show name.
  • Type strings are shortened as expected.
  • mkdocs.yml nav updates (if the script touches it).

Validation

• make docs-reference (ensures generator + templates work and output is updated)
• make docs-check (ensures the docs site still builds)
• (Optional but recommended) make test (sanity check; should be unchanged but cheap to verify)